Packet Reassembler Functions

The following functions can be implemented by packet reassembler components. As noted, some of these functions must be implemented in your component, some can be delegated to the base component, and some are base component utility functions that your component can call.

RTPRssmInitialize

The base reassembler will call this function when it is ready to have your packet reassembler begin handling media packets (this function is not called when the base reassembler opens your component to check its version).



 
ComponentResult RTPRssmInitialize (

                     RTPReassembler rtpr,

                     RTPRssmInitParams *inInitParams);

rtpr: The component instance of your packet reassembler
inInitParams: A pointer to an RTPRssmInitParams struct. Use the information contained in this struct to initialize your component.

RTPRssmReset

This function is called to reset all packet reassembler and base reassembler variables for a new run of data.



 
ComponentResult RTPRssmReset (

                     RTPReassembler rtpr,

                     SInt32 inFlags);

rtpr: The component instance of your reassembler
inFlags: A signed 32-bit integer containing any flags being passed. No flags are currently defined.

DISCUSSION

Be sure to release any packet lists you may have created and decrement to zero the reference counters on any chunks you are maintaining.

RTPRssmComputeChunkSize

The base reassembler will call this function to give your packet reassembler the opportunity to compute the size of a chunk, based on the packet list for the chunk, using your own algorithm. This function is called once for each packet list. Implement this function only if you need to override the base reassembler's default computation.



 
ComponentResult RTPRssmComputeChunkSize (

                     RTPReassembler rtpr,

                     RTPRssmPacket *inPacketListHead,

                     SInt32 inFlags,

                     UInt32 *outChunkDataSize);

rtpr: The component instance of your packet reassembler
inPacketListHead: A pointer to the list of packets that make up this chunk
inFlags: A signed 32-bit integer containing any flags being passed to your packet reassembler.
outChunkDataSize: You should return a pointer to an unsigned 32-bit variable containing the calculated size for this chunk.

DISCUSSION

If you do not implement this call, the base reassembler will compute the chunk size by summing the dataLength for all packets in the list.

RTPRssmAdjustPacketParams

This function is called by the base reassembler when it is processing a packet. This allows your packet reassembler to adjust the packet parameters before the packet is processed.



 
ComponentResult RTPRssmAdjustPacketParams (

                     RTPReassembler rtpr,

                     RTPRssmPacket *inPacket,

                     SInt32 inFlags);

rtpr: The component instance of your packet reassembler
inPacket: A pointer to the RTPRssmPacket struct whose parameters can be adjusted
inFlags: A signed 32-bit integer containing any flags being passed to your packet reassembler.

DISCUSSION

If your packet reassembler does not implement this function, or takes no action, the default for these parameters will be: payloadHeaderLength = fixed header length that is set (default is 0)dataLength = packetData - transportHeaderLength - payloadHeaderLength no serverEditParams chunkFlags = 0

RTPRssmCopyDataToChunk

The base reassembler will call this function to allow your packet reassembler the opportunity to write the chunk data, based on the list of packets for the chunk, using your own algorithm. For example, an H.261 packet reassembler must adjust the byte at packet boundaries. Implement this function only if you need to override the base reassembler's default behavior.



 
ComponentResult RTPRssmCopyDataToChunk (

                     RTPReassembler rtpr,

                     RTPRssmPacket *inPacketListHead,

                     UInt32 inMaxChunkDataSize,

                     SHChunkRecord *inChunk,

                     SInt32 inFlags);

rtpr: The component instance of your packet reassembler
inPacketListHead: A pointer to the RTPRssmPacket struct for the first packet in the list
inMaxChunkDataSize: An unsigned 32-bit integer containing the maximum allowable chunk size
inChunk: A pointer to the chunk record. Write the chunk data to this record.
inFlags: A 32-bit signed integer containing any flags being passed to your media packetizer.

DISCUSSION

If you do not implement this function, the base reassembler will write the chunk data by taking dataLength bytes from each packet in the list, starting at an offset of (packetData + transportHeaderLength + payloadHeaderLength ).

RTPRssmSendPacketList

The base reassembler will call this function when it is ready to create a chunk and send it to the stream handler, based on a list of packets. Implement this call if your packet reassembler needs to modify the packet list, or if it overrides the default handling of packet loss.



 
ComponentResult RTPRssmSendPacketList (

                     RTPReassembler rtpr,

                     RTPRssmPacket *inPacketListHead,

                     const TimeValue64 *inLastChunkPresentationTime,

                     SInt32 inFlags);

rtpr: The component instance of your packet reassembler
inPacketListHead: A pointer to the RTPRssmPacket struct for the first packet in the list
inLastChunkPresentationTime: A pointer to a time value which specifies when to present this chunk, in units of the stream's time scale
inFlags: A signed 32-bit integer containing any flags being passed. The only flag currently defined is: kRTPRssmLostSomePackets = 0x00000001

DISCUSSION

If you do not implement this call, the base reassembler will adjust the packet parameters on all packets in the list, compute the chunk size, and send the chunk. If packet loss has occured, all the packets will be discarded and the stream handler will be informed that the chunk has been lost. If you implement this function inFlags will be set to indicate packet loss if you have instructed to base reassembler to do so in RTPRssmSetCapabilities .

RTPRssmGetTimeScaleFromPacket

If your packet reassembler has not specified a timescale as part of RTPRssmNewStreamHandler , or by calling RTPRssmSetTimeScale , the base reassembler will call this function when it receives packets. This allows your packet reassembler to extract the timescale from a received packet and return it to the base reassembler. The base reassembler will discard received packets until it has been given a valid timescale.



 
ComponentResult RTPRssmGetTimeScaleFromPacket (

                     RTPReassembler rtpr,

                     QTSStreamBuffer *inStreamBuffer,

                     TimeScale *outTimeScale);

rtpr: The component instance of your packet reassembler
inStreamBuffer: A pointer to a received packet from which you may be able to extract a timescale
outTimeScale: Return a pointer to a valid timescale or return an error. If you return a timescale, the packet will be processed normally. Set to zero if you cannot determine the timescale from this packet.

DISCUSSION

Your packet reassembler must set a time scale for the stream handler before the base reassembler can process any incoming packets. If your packet reassembler doesn't know the timescale of its media in advance, because the timescale is contained in the packets for example, the base reassembler will prompt you for a timescale whenever it receives a packet. If your packet reassembler always uses the same timescale, it should set the timescale when it opens a stream handler, and it does not need to implement this function.

RTPRssmSetInfo

This function is called to set various parameters of your packet reassembler. It is also called to set parameters of the base reassembler.



 
ComponentResult RTPRssmSetInfo (

                     RTPReassembler rtpr,

                     OSType inSelector,

                     void *ioParams);

rtpr: The component instance of your packet reassembler
inSelector: A selector for the information being set. Ignore any selectors you do not understand. There are currently no selectors defined.
ioParams: A pointer to a data structure containing the information that should be set.

DISCUSSION

Delegate this function to the base reassembler for any selectors you do not understand. If the base reassembler doesn't understand them either, it will return an error to the caller.

RTPRssmGetInfo

The QTS Toolbox calls this function to obtain information about your packet reassembler.



 
ComponentResult RTPRssmGetInfo (

                     RTPReassembler rtpr,

                     OSType inSelector,

                     void *ioParams);

rtpr: The component instance of your packet reassembler
inSelector: A selector for the information desired. There are currently no selectors defined.
ioParams: A pointer to a data structure appropriate for the type of data requested. If your component understands the selector, write the requested information into the data structure this parameter points to.

DISCUSSION

Implement this function only for the selectors you understand. Delegate this function to the base reassembler for any other selectors. The base reassembler will correctly return an error if it doesn't understand the selector either.

RTPRssmSetCapabilities

Your reassembler calls this function, typically as part of RPTRssmInitialize , to set flags that control the base reassembler.



 
ComponentResult RTPRssmSetCapabilities (

                     RTPReassembler rtpr,

                     SInt32 inFlags,

                     SInt32 inFlagsMask);

rtpr: The component instance of the base reassembler
inFlags: A signed 32 bit integer containing the logical OR of all the flags you are setting. Defined flags are:; kRTPRssmEveryPacketAChunkFlag -- Tells the base reassembler to treat every packet as a chunk, as would be the case for µ-law audio, for example.; kRTPRssmQueueAndUseMarkerBitFlag -- Tells the base reassembler to queue incoming packets and assemble a chunk when a packet has the marker bit set or the RTP time stamp changes.; kRTPRssmTrackLostPacketsFlag -- Tells the base reassembler to check the RTP sequence numbers and set the kRPTRssmLostSomePackets flag if any packets are missing from the packet list when it calls your reassemblers SendPacketList function.; kRTPRssmNoReorderingRequiredFlag -- Tells the base reassembler that packets do not need to come in sequence-number order, as would be the case for µ-law audio, for example.
inFlagsMask: Use this field to preserve the state of any flags you do not wish to alter. If a flag is set in this field, and is not set in the inFlags field, it will not be changed from its current setting.

DISCUSSION

Your packet reassembler can call this function at any time.

RTPRssmGetCapabilities

Your packet reassembler can call this function to obtain the current flag settings for the base reassembler.



 
ComponentResult RTPRssmGetCapabilities (

                     RTPReassembler rtpr,

                     SInt32 *outFlags);

rtpr: The component instance of the base reassembler
outFlags: On return, contains a pointer to the current flags (32-bit signed integer). The flags are described in RTPRssmSetCapabilities.

DISCUSSION

Your packet reassembler can call this function at any time.

RTPRssmSetPayloadHeaderLength

Your packet reassembler calls this function to set a fixed payload header length. If this is not set, the default value is zero.



 
ComponentResult RTPRssmSetPayloadHeaderLength (

                     RTPReassembler rtpr,

                     UInt32 inPayloadHeaderLength);

rtpr: The component instance of the base reassembler
inPayloadHeaderLength: An unsigned 32-bit integer specifying the payload header length, in bytes

DISCUSSION

Call this function during initialization if your packet reassembler works with RTP payloads that contain payload headers of a fixed length.

RTPRssmGetPayloadHeaderLength

Your packet reassembler can call this function to obtain the current value of the fixed payload header length from the base reassembler.



 
ComponentResult RTPRssmGetPayloadHeaderLength (

                     RTPReassembler rtpr,

                     UInt32 *outPayloadHeaderLength);

rtpr: The component instance of the base reassembler component
outPayloadHeaderLength: On return, contains a pointer to an unsigned 32-bit integer containing the length of the payload header in bytes.

f DISCUSSION

Your packet reassembler can call this function at any time.

RTPRssmSetTimeScale

Your packet reassembler uses this function to set the timescale for the stream handler that will render your output. The timescale is the number of time units that pass in one second for the media whose sample data is carried in this stream. The stream handler's timescale must be set before it can deliver any data to the user.



 
ComponentResult RTPRssmSetTimeScale (

                     RTPReassembler rtpr,

                     TimeScale inSHTimeScale);

rtpr: The component instance of the base reassembler
inSHTimeScale: The time scale for the stream handler to use

DISCUSSION

This function is normally called by your packet reassembler when the timescale to use is not initially known. You do not need to call this function if you specified a timescale when the stream handler was opened.

RTPRssmGetTimeScale

Your packet reassembler can call this function to obtain the current timescale from the base reassembler.



 
ComponentResult RTPRssmGetTimeScale (

                     RTPReassembler rtpr,

                     TimeScale *outSHTimeScale);

rtpr: The component instance of the base reassembler
outSHTimeScale: On return, contains a pointer to the timescale in use by the stream handler that is processing your output

RTPRssmNewStreamHandler

This function causes the base reassembler to open a new stream handler. Any currently-opened stream handler will be closed.



 
ComponentResult RTPRssmNewStreamHandler (

                     RTPReassembler rtpr,

                     OSType inSHType,

                     SampleDescriptionHandle inSampleDescription,

                     TimeScale inSHTimeScale,

                     ComponentInstance *outHandler);

rtpr: The component instance of the base reassembler
inSHType: The stream handler type. Use the same constant you would use to specify a track of this type.
inSampleDescription: A handle to a sample description appropriate for this media type. Pass in NULL if you don't know the media type yet. The sample description is passed by reference; the caller is responsible for maintaining it.
inSHTimeScale: The time scale for the stream handler to use. Pass in 0 if the time scale is not yet known.
outHandler: On return, contains a pointer to the component instance of the stream handler that has been opened.

DISCUSSION

Your packet reassembler should call this function when it is initialized.

You must pass in a valid sample description and time scale before the stream handler can process packets. If you do not pass them as part of this function, do so using RTPRssmSetTimeScale and RTPRssmSetSampleDescription .

RTPRssmSendStreamHandlerChanged

Your packet reassembler should call this function when something has changed in the stream and you want the notification propagated (for example, you have changed the dimensions of the video).



 
ComponentResult RTPRssmSendStreamHandlerChanged (RTPReassembler rtpr);

rtpr: The component instance of the base reassembler

DISCUSSION

You will typically receive a series of RTPRssmGetInfo calls to determine what has changed.

RTPRssmSetSampleDescription

Your packet reassembler uses this function to change the sample description being used by the stream handler. All subsequent samples will be marked with this new sample description.



 
ComponentResult RTPRssmSetSampleDescription (

                     RTPReassembler rtpr,

                     SampleDescriptionHandle inSampleDescription);

rtpr: The component instance of the base reassembler
inSampleDescription: The handle of a sample description to use. You are responsible for keeping the handle and the data structure valid during subsequent operations.

DISCUSSION

The sample description is not passed on a per-packet basis, but a per-sample basis, so the sample description should not be changed until a complete sample (sometimes called a "frame" or "chunk") has been reassembled.

RTPRssmGetChunkAndIncrRefCount

Your packet reassembler uses this function to cause the base reassembler to create a chunk for you manually.



 
ComponentResult RTPRssmGetChunkAndIncrRefCount (

                     RTPReassembler rtpr,

                     UInt32 inChunkDataSize,

                     const TimeValue64 *inChunkPresentationTime,

                     SHChunkRecord **outChunk);

rtpr: The component instance of the base reassembler component
inChunkDataSize: An unsigned 32-bit integer containing the size of the chunk's data portion, in bytes
inChunkPresentationTime: A pointer to a 64 -bit time value specifying the time at which this chunk should be presented, in units of the stream's timescale
outChunk: On return, contains a pointer to the newly-created chunk record

DISCUSSION

This function is useful if you are overriding the RTPRssmSendPacketList behavior and constructing the chunk yourself. You must explicitly dispose of the chunk when you are done with it by calling either RTPRssmDecrChunkRefCount or RTPRssmSendChunkAndDecrRefCount.

RTPRssmSendChunkAndDecrRefCount

Your packet reassembler can call this function when it has finished constructing a chunk and wants the base reassembler to send it to the stream handler.



 
ComponentResult RTPRssmSendChunkAndDecrRefCount (

                     RTPReassembler rtpr,

                     SHChunkRecord *inChunk,

                     const SHServerEditParameters *inServerEdit);

rtpr: The component instance of the base reassembler
inChunk: A pointer to a stream handler chunk record
inServerEdit: A pointer to the server edit parameters. Pass in NULL if there is no server edit.

DISCUSSION

Use this function to manually send a chunk if you have overridden the default behavior of RTPRssmSendPacketList . This function will decrement the refcount of the chunk. If the refcount is then zero, the chunk is deallocated.

RTPRssmSendLostChunk

Your packet reassembler can use this function to cause the base reassembler to send loss notification to the stream handler.



 
ComponentResult RTPRssmSendLostChunk (

                     RTPReassembler rtpr,

                     const TimeValue64 *inChunkPresentationTime);

rtpr: The componentinstance of the base reassembler
inChunkPresentationTime: A pointer to a 64-bit time value indicating when the chunk would have been presented, in units of the stream's time scale

DISCUSSION

Loss notification is normally performed automatically by the base reassembler. Use this function if you are handling loss and sending chunks manually. Call this function if the chunk you have built will not be sent.

RTPRssmClearCachedPackets

Your packet reassembler uses this function to cause the base reassembler to flush all packets currently queued in its lists.



 
ComponentResult RTPRssmFlushPackets (RTPReassembler rtpr);

rtpr: The component instance of the base reassembler

DISCUSSION

This function is only useful when the base reassembler is operating with the kRTPRssmQueueAndUseMarkerBit flag set.

RTPRssmReleasePacketList

Use this function to release the memory associated with a packet list that your packet reassembler created itself, or a list your reassembler took ownership of as a result of implementing RTPRssmSendPacketlist .



 
ComponentResult RTPRssmReleasePacketList (

                     RTPReassembler rtpr,

                     RTPRssmPacket *inPacketListHead);

rtpr: The component instance of the base reassembler
inPacketListHead: A pointer to the RTPRssmPacket struct of the first packet in packet list to dispose of

DISCUSSION

This is a housekeeping function that you do not need to perform for packet lists created and handled by the base reassembler, only for packet lists that you create or take ownership of yourself.

RTPRssmIncrChunkRefCount

Use this function to tell the base reassembler to keep a copy of a chunk, to assist in loss recovery, for example.



 
ComponentResult RTPRssmIncrChunkRefCount (

                     RTPReassembler rtpr,

                     SHChunkRecord *inChunk);

rtpr: The component instance of the base reassembler
inChunk: A pointer to the chunk record you want to preserve

DISCUSSION

You must call RTPRssmDecrChunkRefCount to release the chunk when you no longer need it.

RTPRssmDecrChunkRefCount

Tell the base reassembler to devrement the reference counter of a chunk that it has created or preserved for you. If the reference count becomes zero, the chunk is deallocated.



 
ComponentResult RTPRssmDecrChunkRefCount (

                     RTPReassembler rtpr,

                     SHChunkRecord *inChunk);

rtpr: The component instance of the base reassembler component
inChunk: A pointer to the chunk record to dispose

DISCUSSION

If you have overriden the RTPRssmSendPacketList behavior, and are instructing the base reassembler to construct chunks manually, your packet assembler must explictly dispose of the chunks by calling either RTPRssmDecrChunkRefCount or RTPRssmSendChunkAndDecrRefCount . This function is also used to release a chunk you have preserved using the RTPRssmIncrChunkRefCount function.